<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
<head>
    <title>UrlRewriteFilter - Annotation</title>
    <style type="text/css">
        @import url( "doc.css" );
    </style>
</head>

<body>

<div id="masthead">
    <a href="http://www.tuckey.org/urlrewrite/">
         <img src="http://www.tuckey.org/img/urlrewrite.gif" border="0" alt="Tuckey Logo" />
        Url Rewrite Filter 3.0</a>
</div>

<div id="menu">
<ul>
    <li><a href="http://www.tuckey.org/urlrewrite/">Home</a></li>
    <li><a href="http://www.tuckey.org/urlrewrite/#download">Download</a></li>
    <li><a href="https://github.com/paultuckey/urlrewritefilter">GitHub Project</a></li>
    <li><a href="http://stackoverflow.com/questions/tagged/tuckey-urlrewrite-filter">UrlRewrite on StackOverflow</a><br/>&nbsp;</li>

    <li><b>Background</b>
        <ul>
            <li><a href="introduction.html#license">License</a></li>
            <li><a href="introduction.html#changelog">Changelog</a></li>
        </ul>
    </li>
    <li><a href="index.html">Configuration</a>
        <ul>
            <li><a href="index.html#install">Install</a></li>
            <li><a href="index.html#tips">Tips</a></li>
            <li><a href="index.html#filterparams">Filter Parameters</a></li>
            <li><a href="index.html#configuration">Configuration File</a></li>
            <li><a href="index.html#anttask">Ant Task</a></li>
        </ul>
    </li>
    <li>Annotations</li>
    <li><a href="guide.html">Examples</a>
        <ul>
            <li><a href="guide.html#method">Method Invocation</a></li>
            <li><a href="guide.html#urlabs">URL Abstraction</a></li>
            <li><a href="guide.html#mod_re">mod_rewrite vs UrlRewriteFilter</a></li>
        </ul>
    </li>
    <li>Annotations</li>
</ul>
</div>

<div id="main">

    <div class="outdated"><a href=../index.html>Latest Documentation</a></div>

    <h1>URL Matching Annotations</h1>

<a name="annotation"></a>

<p>EXPIREMENTAL support for annotations has been added as part of 3.0 development.
    You must be using JDK 1.5 for this to work.</p>

    <p>The intention of annotations in UrlRewriteFilter is purely for conf file generation.  The is NO runtime
    dependency on the annotations.</p>

    <h2>Annotations</h2>

    <h3>@HttpUrl</h3>

    <p>Set the method up to be used when the url is Matched, matched groups are assigned to method paramters (if any).</p>

    <pre><code>
        @HttpUrl("^/do-something/([0-9]+)$")
        void doSomething(Long id)
    </code></pre>

    <p>When a request for /do-something/1234, doSomething is called with id set to 1234.</p>

    <h3>@HttpParam</h3>

    <p>Sets the parameter from request.getParameter (handles type conversion as necessary)</p>

    <pre><code>
        void doSomething(@HttpParam String name, @HttpParam long id, @HttpParam("uid") Long userId)
    </code></pre>

    <p>The above example will:
        <br/>name = request.getParameter("name");
        <br/>id = convertTolongDefault0(request.getParameter("id"));
        <br/>userId = convertToLongDefaultNull(request.getParameter("uid"));
        <br/>An exception will never be thown during type conversion
    </p>




<h2>Conf Generation</h2>

    <p>Add a post-compile step to your build script.</p>

   <pre><code>
        &lt;target name="compile-urlrewrite-conf"&gt;
            &lt;path id="annotation-classpath"&gt;
                &lt;path refid="compile.classpath"/&gt;
                &lt;path refid="compiled.classpath"/&gt;
                &lt;fileset file="${jdk.home}/lib/tools.jar"/&gt;
            &lt;/path&gt;
            &lt;fileset id="sources" dir="." includes="src/**/actions/**/*.java"/&gt;
            &lt;pathconvert pathsep=" " property="sourcefiles" refid="sources"/&gt;
            &lt;!-- helpful for debugging classpath issues
                &lt;property name="prop-annotation-classpath" refid="annotation-classpath"/&gt;
                &lt;echo&gt;
                CLASSPATH ${prop-annotation-classpath}
                SOURCES: ${sourcefiles}
                &lt;/echo&gt; --&gt;
            &lt;exec executable="apt"&gt;
                &lt;arg value="-classpath"/&gt;
                &lt;arg pathref="annotation-classpath"/&gt;
                &lt;arg value="-nocompile"/&gt;
                &lt;arg value="-factory"/&gt;
                &lt;arg value="org.tuckey.web.filters.urlrewrite.annotation.HttpUrlAPTFactory"/&gt;
                &lt;arg value="-AsaveRulesTo=build/web/WEB-INF/urlrewrite-generated.xml"/&gt;
                &lt;arg line="${sourcefiles}"/&gt;
            &lt;/exec&gt;
        &lt;/target&gt;
    </code></pre>

    <p>This will generate to the file specified.  Any errors will be output to stdout using the standard APT method.
    Read the generated conf file and check it for errors.</p>


<p>Include the compiled conf file in your normal conf.</p>

<pre><code>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 3.0//EN"
        "http://www.tuckey.org/res/dtds/urlrewrite3.0.dtd"
[
    &lt;!ENTITY included SYSTEM "urlrewrite-generated.xml"&gt;
]&gt;
&lt;!--

    Configuration file for UrlRewriteFilter
    http://www.tuckey.org/urlrewrite/

--&gt;
&lt;urlrewrite&gt;

    &lt;!--
        other rules...
    --&gt;

    &included;


&lt;/urlrewrite&gt;
</code></pre>


<p>Check your /rewrite-status for errors if things start going strange.</p>

</div>

<div id="footer">
Copyright Paul Tuckey <!--@year-->2007<!--/@year-->
    - <a href="http://www.tuckey.org/urlrewrite/">UrlRewirteFilter</a>
</div>

</body>
</html>

